Plotting tools
==============

RISE ships a number of plotting helpers that fall into three groups:

- **Time-series plotters** -- methods on the ``ts`` class (``plot``,
  ``fanchart``, ``plot_decomp``) and the corresponding standalone
  routines that consume their output.
- **Model plotters** -- one-call convenience methods on ``dsge`` / VAR
  objects (``quick_irfs``, ``quick_plots``, ``plot_probabilities``,
  ``plot_data_against_probabilities``).
- **Decorations and layout** -- shaded recession bands, super-labels
  across subplot grids, x-tick rotation, multi-panel layout helpers,
  date-tick handling.

Plus a save-figure utility and the default figure / print settings
applied automatically by ``rise_startup``.

The ``myplot`` wrapper
----------------------

``utils.plot.myplot`` is the central plotting routine that every
``ts``-aware method calls into (``ts.plot``, ``ts.bar``, ``ts.area``,
``ts.errorbar``, ...). It wraps an arbitrary plot function and adds:

- automatic handling of ``ts`` inputs (multi-column, multi-page);
- date-aware x-axis (frequency-specific tick labels via
  ``plot_specs``);
- optional date-range filtering (pass a ``dates`` range as the first
  positional argument);
- log-scale toggles and other RISE-specific options.

The user rarely calls ``myplot`` directly; it surfaces through ``ts``
methods. Knowing it exists explains why ``ts.plot(...)`` accepts
extras that bare ``plot`` does not.

Time-series plotters
--------------------

Fan charts
~~~~~~~~~~

Two-step process:

#. Build the fan data from a ``ts`` object that holds either pages or
   columns (not both)::

       data = fanchart(myts, ci);

   ``ci`` is a vector of confidence levels in ``[0, 1]`` or ``[0, 100]``.
   The returned struct has fields ``ci``, ``median``, ``variance``,
   ``quantiles``, ``prob_index``, ``probs``.

#. Plot it::

       plot_fanchart(data)
       plot_fanchart(data, MainColor)
       plot_fanchart(data, MainColor, nticks)
       hh = plot_fanchart(...)

   ``MainColor`` accepts a single-character colour code
   (``'c','b','g','r','m','k','w'``), an RGB triplet, or ``'nb'`` (the
   default; assumes exactly 4 quantile bands). ``nticks`` is the number
   of x-axis ticks (default ``8``).

Decomposition bar plots
~~~~~~~~~~~~~~~~~~~~~~~

``plot_decomp`` stacks positive and negative contributions as bars
and overlays the total as a line. The ``ts``-method form and the
standalone form coexist::

    plot_decomp(ts1, ..., 'Name', Value, ...)
    plot_decomp(xrange, ts1, ..., 'Name', Value, ...)

The optional ``xrange`` (e.g. ``rq(2020,1):rq(2022,4)``) restricts the
plot to a date window. Each ``ts`` argument has one column per
component; the total line is the sum of the columns. Name-value pairs
are forwarded to ``plot``.

Model plotters
--------------

These take a solved model object as input and produce publication-shaped
multi-panel figures with sensible defaults.

``quick_irfs``
~~~~~~~~~~~~~~

::

    hdl = quick_irfs(m, myirfs, var_list, shock_list, r0c0, xrange, suplab, leGend)

Lays out impulse-response panels: one figure per shock, one subplot per
variable. ``myirfs`` is the structure returned by ``irf``; ``var_list``
and ``shock_list`` filter the rows and figures; ``r0c0 = [rows, cols]``
controls the grid (default ``[4, 4]``); ``xrange`` restricts horizons;
``suplab`` adds a super-label across the grid; ``leGend`` adds a legend.

``quick_plots``
~~~~~~~~~~~~~~~

Generic counterpart for arbitrary post-solve series (forecasts,
simulations, historical decompositions). Same layout idea, same set of
optional arguments (``var_list``, ``fig_title``, ``r0c0``, ...). Two
forms:

- ``quick_plots(m, batch, ...)`` -- as a ``@generic`` method.
- ``utils.plot.quick_plots(description, batch, ...)`` -- standalone
  with an explicit ``description`` struct rather than a model.

Smoothed probabilities
~~~~~~~~~~~~~~~~~~~~~~

::

    plot_probabilities(model)
    plot_probabilities(model, specs, stateList, regimeList, shadeInfo, description)

For Markov-switching ``dsge`` / VAR models. Plots the smoothed
probabilities of states (``stateList``) and / or regimes
(``regimeList``). ``specs = [rows, cols]`` sets the grid; ``shadeInfo``
is an optional function handle (typically wrapping ``shade``) that adds
shaded bands; ``description`` is an optional struct overriding labels.

::

    plot_data_against_probabilities(model, type, specs, shadeInfo, description)

Overlays the observed data against the smoothed state or regime
probabilities. ``type`` is ``'state'`` or ``'regime'``, optionally with
a variable list.

Decorations and layout
----------------------

``shade``
~~~~~~~~~

::

    shade(start_finish)
    shade(start_finish, color)
    shade(start_finish, color, fig)

Adds shaded vertical bands to an existing plot. ``start_finish`` is
either an ``n x 2`` matrix of date pairs or a logical ``ts`` whose
``true`` intervals define the shaded periods. Default colour is light
grey ``[211, 211, 211] / 255``. The shading respects current y-limits
and sits behind plotted data; works on tiled and multi-axes figures.

``recession_dates``
~~~~~~~~~~~~~~~~~~~

::

    r = recession_dates(F)

NBER recession periods at frequency ``F`` (``'D'``, ``'W'``, ``'M'``,
``'Q'``, ``'H'``, ``'Y'``; default ``'Q'``). Returns a cell array of
``[start, end]`` date pairs ready to feed into ``shade``.

``sup_label``
~~~~~~~~~~~~~

::

    [ax, h] = sup_label(text, whichLabel, supAxes)
    ax     = sup_label(text, whichLabel, supAxes)

Places a single ``title`` / ``xlabel`` / ``ylabel`` spanning a group of
subplots (``whichLabel`` selects which). Returns handles to the
super-axis (and optionally to the text). Lifted from Ben Barrowes'
``suplabel`` on File Exchange, with minor RISE-specific tweaks.

``xrotate``
~~~~~~~~~~~

::

    xrotate()        % default 90 degrees
    xrotate(angle)   % numeric or string

Rotates x-axis tick labels for every Cartesian axis in the current
figure. Skips polar / geographic axes.

``number_of_rows_and_columns_in_figure``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

::

    [Remains, r, c] = number_of_rows_and_columns_in_figure(fig, nvar, r0, c0)

Tiles ``nvar`` variables across the current figure with up to ``r0``
rows and ``c0`` columns per page. ``Remains`` is what didn't fit on
this page, intended to be passed back in a loop until empty.

``plot_specs``
~~~~~~~~~~~~~~

::

    pp = plot_specs(serial_dates, nticks)

Computes x-axis values, tick locations and labels, and x-limits from
a serial-date vector. Used internally by ``myplot`` to honour
frequency-specific date formatting; useful directly only when bypassing
``myplot`` to drive a non-RISE plot routine off RISE dates.

Saving figures
--------------

``save_figure``
~~~~~~~~~~~~~~~

::

    save_figure(figHandle, baseName, resDir)
    save_figure(figHandle, baseName, resDir, nvp)

Writes a figure to disk in any combination of ``.fig``, ``.png``,
``.pdf``, ``.svg``, ``.jpeg``, working on a temporary copy so the
original figure is left untouched. By default applies a "tight" layout
pass that minimises whitespace around plotted content -- the result is
suited to direct inclusion in LaTeX / Beamer documents without manual
trimming. ``baseName`` may include a path (in which case ``resDir`` is
ignored). The ``nvp`` struct controls formats, tightness, and a few
other options.

Default figure and print settings
---------------------------------

``rise_startup`` configures MATLAB's root-level figure paper properties
so that any figure later printed picks up landscape A4 with a sensible
content box. The relevant assignments::

    set(0, 'DefaultFigurePaperOrientation', 'landscape');
    set(0, 'DefaultFigurePaperType',        'A4');
    set(0, 'DefaultFigurePaperUnits',       'centimeters');
    set(0, 'DefaultFigurePaperPositionMode','manual');
    set(0, 'DefaultFigurePaperPosition',    [3.56  2.03  22.56  16.92]);

These are root defaults; they propagate to every figure created after
``rise_startup`` unless explicitly overridden on the figure itself.
``rise_exit`` restores them to MATLAB factory values.

Two practical consequences:

- ``print(fig, '-dpdf', ...)`` and ``save_figure(fig, ..., 'pdf')``
  produce landscape PDFs at the configured size by default. No
  per-figure paper setup is needed before printing.
- If you want a different paper geometry, override on the figure
  (``set(fig, 'PaperPosition', ...)``) rather than on the root --
  per-figure settings take precedence.